docs: add comprehensive generalized wrappers documentation#595
Open
docs: add comprehensive generalized wrappers documentation#595
Conversation
Add complete documentation for CoW Protocol's generalized wrappers feature
across three audience-specific files:
- concepts/order-types/wrappers.md: High-level overview explaining what
wrappers are, use cases (Euler leverage, flash loans, TWAP, protocol hooks),
benefits, and considerations
- integrate/wrappers.mdx: Practical integration guide with three sections:
* For Order Creators: How to add wrappers to orders via appData
* For Wrapper Developers: Building custom wrapper contracts with security
requirements and implementation examples
* For Solvers: Encoding wrapper settlements and handling wrapper execution
- reference/contracts/periphery/wrapper.mdx: Smart contract reference focused
on ICowWrapper interface, CowWrapper abstract contract, implementation
patterns, and on-chain behavior
Each file serves a distinct purpose and audience while cross-linking to
provide comprehensive coverage of the wrapper system.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdds three new documentation pages introducing Generalized Wrappers for the CoW Protocol: a conceptual overview, an integration guide, and a technical reference covering wrapper architecture, data encoding, execution flow, and security considerations. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
rect rgba(200,220,255,0.5)
participant User
participant Solver
participant Authenticator
participant WrapperA as Wrapper (A)
participant WrapperB as Wrapper (B)
participant Settlement as SettlementContract
participant External as ExternalProtocol
end
User->>Solver: submit order + appData.wrappers
Solver->>Authenticator: validate wrapper allowlist
Authenticator-->>Solver: allow / deny
alt allowed
Solver->>WrapperA: call wrappedSettle(dataA, next=WrapperB)
WrapperA->>WrapperA: _wrap pre-settlement logic
WrapperA->>WrapperB: _next(pass remaining data)
WrapperB->>WrapperB: _wrap pre/post logic
WrapperB->>Settlement: _next -> call settlement target
Settlement->>External: execute settlement (swaps, transfers)
External-->>Settlement: settlement result
Settlement-->>WrapperB: return
WrapperB->>WrapperA: return (post-settle)
WrapperA-->>Solver: final return
else denied
Authenticator-->>Solver: revert / reject
end
Estimated code review effort🎯 2 (Simple) | ⏱️ ~15 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
📝 Coding Plan
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 14
🤖 Fix all issues with AI agents
In `@docs/cow-protocol/concepts/order-types/wrappers.md`:
- Line 44: Fix the spelling in the header "### Progmatic Orders" by changing it
to "### Programmatic Orders" in the docs file; locate the header string
"Progmatic Orders" and replace it with "Programmatic Orders" so the section
title is correct.
- Line 7: Fix the typos and punctuation in the "Generalized wrappers" sentence:
change "progmatic" to "programmatic" and replace the double dash "--" with an em
dash "—" (or a comma) so the sentence reads cleanly (e.g., "...like flash loans,
leveraged positions, and programmatic orders— all while preserving..."). Update
the sentence in the wrappers.md content where "Generalized wrappers is a new
framework..." appears.
- Line 17: Fix typos and minor wording in the paragraph: change "guarenteed" to
"guaranteed", remove the extra space before "wrappers" so it reads "audited and
wrappers" properly as "audited wrappers" (or "audited and wrappers" -> remove
stray "and" if intended), change "solver" to plural "solvers", and lowercase
"Wrapper functionality" to "wrapper functionality" for consistency; update the
sentence in the docs content (the paragraph referencing
GPv2AllowlistAuthenticator and settlement contract) accordingly.
- Line 74: Update the phrase "high quality wrapper implementations" to use a
hyphenated compound adjective: change it to "high-quality wrapper
implementations" in the sentence describing the approval process by the
allowlist authenticator and CoW DAO (the sentence beginning "Wrappers cannot be
deployed..."). Ensure the hyphen is added only when "high-quality" directly
modifies "wrapper implementations."
- Line 92: Update the broken link pointing to
../../reference/contracts/periphery/wrapper.md by changing its extension to .mdx
(../../reference/contracts/periphery/wrapper.mdx) in the text "**For technical
specs**" inside the wrapper documentation; locate the markdown link string
"../../reference/contracts/periphery/wrapper.md" and replace ".md" with ".mdx"
so it points to the correct Technical Reference file (wrapper.mdx).
In `@docs/cow-protocol/integrate/wrappers.mdx`:
- Line 131: Replace the placeholder link in the sentence "Wrappers are specified
in the order's [`appData`](TODO) under the `wrappers` field" with the actual
documentation path for appData: locate the appData docs by searching the repo
for the "appData" heading or file (the page that documents order.appData), then
update the TODO to that MDX/URL (use a relative docs path or absolute docs URL
consistent with other links in docs/cow-protocol/integrate/wrappers.mdx) so the
link points directly to the appData section.
- Line 320: Replace the misspelled word "simpulate" with "simulate" in the
sentence that reads "Account for wrapper gas overhead in your bids. The easiest
way to do this is to simpulate the wrapper transaction against an empty
settlement." so it reads "...simulate the wrapper transaction against an empty
settlement."; locate that exact sentence to make the single-word correction.
- Line 164: Update the incorrect documentation link: change the path string in
the sentence referencing GPv2AllowlistAuthenticator from
../references/contracts/core/allowlist.md to
../reference/contracts/core/allowlist.md so the link points to the existing
reference directory and continues to mention GPv2AllowlistAuthenticator for
context.
- Line 343: Update the broken link in docs/cow-protocol/integrate/wrappers.mdx
by changing the reference from "../reference/contracts/periphery/wrapper.md" to
"../reference/contracts/periphery/wrapper.mdx" so it points to the actual
wrapper.mdx file; locate the link text "**[Contracts
Reference](../reference/contracts/periphery/wrapper.md)**" and replace the .md
extension with .mdx.
- Line 8: The navigation link in docs/cow-protocol/integrate/wrappers.mdx has
mismatched bold markers around the link text ("Executing Wrappers as a Solver"
with anchor "#for-solvers") causing formatting issues; fix it by making the bold
markers balanced — either wrap the entire link and trailing description in
**...** or remove the leading ** so the link uses normal markdown; update the
line containing the "[Executing Wrappers as a Solver](`#for-solvers`) - Everything
solvers need to know to execute wrapper orders" text to have correct opening and
closing bold markers.
- Around line 254-257: The docs use two different names for the same
value—chainedWrapperData vs wrapperData—causing confusion in the call to
wrapperContract.interface.encodeFunctionData("wrappedSettle"); make the names
consistent by either (A) changing the second parameter in the encodeFunctionData
call from chainedWrapperData to wrapperData, or (B) updating the earlier
function that returns wrapperData to return/mention chainedWrapperData instead;
ensure the comment "From step 3" and the variable name used in wrappedSettle's
argument list (wrapperData/chainedWrapperData) match exactly.
In `@docs/cow-protocol/reference/contracts/periphery/wrapper.mdx`:
- Line 477: Replace the misspelled word "reccomended" with "recommended" in the
sentence that reads "It is reccomended to use
[Cannon](https://usecannon.com/learn) to make it easy to redeploy your
wrappers." (search for the exact string "reccomended" in the wrapper.mdx content
to locate the spot).
- Line 283: Fix the spelling mistake in the documentation: change "reccomended"
to "recommended" in the sentence mentioning ICowWrapper and CowWrapper so it
reads "It is strongly recommended to **NOT** implement `ICowWrapper` directly.
The `CowWrapper` abstract contract provides:". Update the phrase near the
references to ICowWrapper and CowWrapper accordingly.
- Around line 129-134: Fix the malformed Markdown code block under the
"Example:" section by converting the loose fenced text into a proper fenced code
block: ensure the "Example:" label is followed by a fenced block using ```text,
include the two lines "[0x0005][0xAABBCCDDEE][0x1234...ABCD][0x0003][0x112233]"
and "↑len ↑data ↑next wrapper ↑len ↑data" exactly as shown, and
close the block with ``` so the snippet displays correctly in the docs reference
for wrapper.mdx.
🧹 Nitpick comments (1)
docs/cow-protocol/reference/contracts/periphery/wrapper.mdx (1)
43-43: Clarify incomplete phrase."allowing CoW orders" appears incomplete. Perhaps it should be "allowing multiple CoW orders to use different wrappers in the same batch" or similar?
📝 Suggested clarification
-3. **Nested Support**: Multiple wrappers chain by encoding addresses sequentially, allowing CoW orders +3. **Nested Support**: Multiple wrappers chain by encoding addresses sequentially, allowing multiple orders with different wrappers in the same settlement batch
|
|
||
| ### Wrapper Authentication | ||
|
|
||
| For security, all wrappers must be approved through CoW Protocol's `GPv2AllowlistAuthenticator` before they can be used. This ensures that only audited and wrappers can interact with the settlement contract, protecting users, solver, and the protocol from malicious contracts. Unlike [hooks](./cow-hooks.mdx), Wrapper functionality can revert the execution of a transaction, ensuring sensitive user operations such as cross-chain operations can be guarenteed to be completed. |
Contributor
There was a problem hiding this comment.
Fix spelling error.
"guarenteed" should be "guaranteed".
✍️ Proposed fix
-For security, all wrappers must be approved through CoW Protocol's `GPv2AllowlistAuthenticator` before they can be used. This ensures that only audited and wrappers can interact with the settlement contract, protecting users, solver, and the protocol from malicious contracts. Unlike [hooks](./cow-hooks.mdx), Wrapper functionality can revert the execution of a transaction, ensuring sensitive user operations such as cross-chain operations can be guarenteed to be completed.
+For security, all wrappers must be approved through CoW Protocol's `GPv2AllowlistAuthenticator` before they can be used. This ensures that only audited wrappers can interact with the settlement contract, protecting users, solvers, and the protocol from malicious contracts. Unlike [hooks](./cow-hooks.mdx), wrapper functionality can revert the execution of a transaction, ensuring sensitive user operations such as cross-chain operations can be guaranteed to be completed.Note: Also fixed "solver" → "solvers", removed extra space before "wrappers", and capitalization of "Wrapper functionality" → "wrapper functionality" for consistency.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| For security, all wrappers must be approved through CoW Protocol's `GPv2AllowlistAuthenticator` before they can be used. This ensures that only audited and wrappers can interact with the settlement contract, protecting users, solver, and the protocol from malicious contracts. Unlike [hooks](./cow-hooks.mdx), Wrapper functionality can revert the execution of a transaction, ensuring sensitive user operations such as cross-chain operations can be guarenteed to be completed. | |
| For security, all wrappers must be approved through CoW Protocol's `GPv2AllowlistAuthenticator` before they can be used. This ensures that only audited wrappers can interact with the settlement contract, protecting users, solvers, and the protocol from malicious contracts. Unlike [hooks](./cow-hooks.mdx), wrapper functionality can revert the execution of a transaction, ensuring sensitive user operations such as cross-chain operations can be guaranteed to be completed. |
🧰 Tools
🪛 LanguageTool
[grammar] ~17-~17: Ensure spelling is correct
Context: ...s such as cross-chain operations can be guarenteed to be completed. ### Wrapper Nesting ...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🤖 Prompt for AI Agents
In `@docs/cow-protocol/concepts/order-types/wrappers.md` at line 17, Fix typos and
minor wording in the paragraph: change "guarenteed" to "guaranteed", remove the
extra space before "wrappers" so it reads "audited and wrappers" properly as
"audited wrappers" (or "audited and wrappers" -> remove stray "and" if
intended), change "solver" to plural "solvers", and lowercase "Wrapper
functionality" to "wrapper functionality" for consistency; update the sentence
in the docs content (the paragraph referencing GPv2AllowlistAuthenticator and
settlement contract) accordingly.
Contributor
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Fix all issues with AI agents
In `@docs/cow-protocol/concepts/order-types/wrappers.md`:
- Line 11: In the sentence starting "Wrappers are smart contracts that 'wrap'
the settlement process..." replace "surrounding settlement contract" with
"surrounding the settlement contract" so the phrase reads "executing custom
logic surrounding the settlement contract" to correct the missing article;
locate the phrase in wrappers.md and update that sentence accordingly.
- Around line 52-54: Replace the inconsistent "Cross chain transfers (pre- or
post- transfer)" phrase with a hyphenated form: "Cross-chain transfers (pre- or
post-transfer)" so it matches the existing "cross-chain" usage and also
hyphenates "post-transfer"; update the exact line containing the phrase "Cross
chain transfers" in the document.
In `@docs/cow-protocol/integrate/wrappers.mdx`:
- Around line 12-16: Multiple subsection headings (e.g., "Overview", "Adding
Wrappers to Orders", "Detecting Wrapper Orders" and other similar entries) are
incorrectly using "##" and therefore sit at the same level as the three main
audience headings ("For Wrapper Developers", "For Order Creators…", "For
Solvers"); change these subsection headings from "##" to "###" so they become
children of their respective audience sections (update every occurrence
referenced in the comment such as the "Overview", "Adding Wrappers to Orders",
"Detecting Wrapper Orders" headings and the other instances mentioned) to
restore proper heading hierarchy and TOC nesting.
- Around line 217-237: The encodeWrapperData function assumes wrapper.data
always exists and uses wrapper.data.length and slice, which breaks when
WrapperCall.data is optional; update encodeWrapperData to normalize data per
wrapper (e.g., const data = wrapper.data ?? '0x'; if (data === '') data = '0x'),
compute dataLength safely as Math.max(0, (data.length - 2) / 2), generate
lengthHex from that number, and only append data.slice(2) when dataLength > 0;
apply these changes in the encodeWrapperData function so it handles undefined or
empty wrapper.data without throwing.
🧹 Nitpick comments (1)
docs/cow-protocol/integrate/wrappers.mdx (1)
298-314: Wrapper accumulation example blindly collects duplicates.The conceptual example pushes all wrappers from all orders without deduplication. If two orders reference the same wrapper, it would appear twice. Consider adding a comment or dedup logic to clarify expected behavior for readers.
pretf00d
reviewed
Feb 16, 2026
pretf00d
reviewed
Feb 16, 2026
pretf00d
reviewed
Feb 16, 2026
pretf00d
reviewed
Feb 16, 2026
pretf00d
reviewed
Feb 16, 2026
pretf00d
reviewed
Feb 16, 2026
pretf00d
reviewed
Feb 16, 2026
pretf00d
reviewed
Feb 16, 2026
|
|
||
| ## Detecting Wrapper Orders | ||
|
|
||
| Wrappers are specified in the order's [`appData`](../reference/core/auctions/schema.md) under the `wrappers` field: |
Author
There was a problem hiding this comment.
I believe the grammar is it is now is correct here. The appData is "possessed" by the order.
pretf00d
reviewed
Feb 16, 2026
pretf00d
reviewed
Feb 16, 2026
pretf00d
reviewed
Feb 16, 2026
pretf00d
reviewed
Feb 16, 2026
fedgiac
reviewed
Mar 11, 2026
Comment on lines
+112
to
+115
| const isValid = await helper.verifyAndBuildWrapperData( | ||
| ["0x1234...", "0x5678..."], // Wrapper addresses | ||
| ["0xabcd...", "0xef01..."] // Wrapper data | ||
| ) |
Contributor
There was a problem hiding this comment.
Inconsistent with the actual function:
function verifyAndBuildWrapperData(WrapperCall[] memory wrapperCalls)
| #### 2. Verify Wrapper Authentication | ||
|
|
||
| All approved wrappers will be approved by the DAO and registered in [`GPv2AllowlistAuthenticator`](../reference/contracts/core/allowlist.md). It is recommended to verify wrappers are allowlisted before including them in settlements. | ||
|
|
Contributor
There was a problem hiding this comment.
I think there should be an extra step here: decide whether to include the order in the settlement or not.
Since wrappers are likely to have complex behaviors, they would have to assess the revert risk based on the concrete wrapper implementation and may decide to skip it or adjust the scoring of the settlement accordingly.
Author
There was a problem hiding this comment.
Do we have any specific advice on how to actually do that? I don't, other than simulating the order (which we already do in the driver and sometimes autopilot...). Seems like something we have to discuss. See previous comment about adding new wrappers and lack of solver involvement.
Author
There was a problem hiding this comment.
Added additional docs here advising to simulate the transaction and perform any checks that may be necessary, especially confirming the transaction reverts or not 42ac22b
Contributor
There was a problem hiding this comment.
which we already do in the driver and sometimes autopilot
The solver doesn't have to use the official driver. The driver does some checks, but solvers should know which of them are needed. A solver may be using the official driver, but it doesn't have to and the docs should reflect that.
For the autopilot, "sometimes" isn't enough, and even if it was "always," that's still not ideal because we don't want to add more responsibilities to the autopilot. We shouldn't use the autopilot as a gatekeeper (similar discussion here).
fedgiac
reviewed
Mar 11, 2026
Co-authored-by: Federico Giacon <58218759+fedgiac@users.noreply.github.com>
Co-authored-by: Federico Giacon <58218759+fedgiac@users.noreply.github.com>
Co-authored-by: Federico Giacon <58218759+fedgiac@users.noreply.github.com>
overall reduce verbosity, link to maintainable sources when applicable, reduce duplication, and improve clarifications in some places
Author
|
benyond just your general comments @fedgiac , I explicitly tried to remove anything repetative from the docs, explicitly prioritizing links to maintainable code on github or other pages if the doc is already there, throughout all pages. LMK if I missed anything! |
fedgiac
reviewed
Mar 13, 2026
Comment on lines
+129
to
+132
| The CoW Wrapper Helpers contract is deployed via `CREATE2`, and is being rolled out to the following addresses on each network supported by CoW: | ||
| * Production: `0x8C8f88F3081A7d54fCbC2Bd7C6Cf5E9Fc26e30E9` | ||
| * Staging: `0xfd1a35C8E7AEC58a4bB6AeDca0B2Bf9c9Be9E07F` | ||
|
|
Contributor
There was a problem hiding this comment.
Can you move this to this page and add a link here for consistency?
Eventually I hope we change how we generate that page thanks to the new deployment repo!
Co-authored-by: Federico Giacon <58218759+fedgiac@users.noreply.github.com>
Co-authored-by: Federico Giacon <58218759+fedgiac@users.noreply.github.com>
Co-authored-by: Federico Giacon <58218759+fedgiac@users.noreply.github.com>
Co-authored-by: Federico Giacon <58218759+fedgiac@users.noreply.github.com>
Co-authored-by: Federico Giacon <58218759+fedgiac@users.noreply.github.com>
…ery contracts page where it belongs
fedgiac
reviewed
Mar 17, 2026
Contributor
fedgiac
left a comment
fedgiac
left a comment
There was a problem hiding this comment.
Looks good to me. Not approving because the build failed, but once that's sorted out it can be merged.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Add complete documentation for CoW Protocol's generalized wrappers feature across three audience-specific files:
Changes
concepts/order-types/wrappers.md: High-level overview explaining what wrappers are, use cases (Euler leverage, flash loans, TWAP, protocol hooks), benefits, and considerationsintegrate/wrappers.mdx: Practical integration guide with three sections:reference/contracts/periphery/wrapper.mdx: Smart contract reference focused on ICowWrapper interface, CowWrapper abstract contract, implementation patterns, and on-chain behaviorSummary by CodeRabbit